Git LFS

Git Large File Storage。让 Git 仓库优雅地管理大二进制文件（图片、视频、PDF、设计稿等），同时保持 git clone、git pull、git diff 的体验不被巨型 blob 拖死。

在 wiki-vault 里，你完全不需要主动用 LFS。.gitattributes 已配，正常 git add 就走 LFS。

它解决什么问题

Git 设计假设是"小文本 + 频繁修改"。一个 5MB 的 PNG，每改一像素 git 都要把整张图重存一份。仓库会从几 MB 暴涨到几 GB，导致：

• git clone 几十分钟
• git push 失败或超时
• CI 资源浪费
• 历史不可回溯

LFS 把"大文件"和"git 仓库"解耦：

• Git 仓库里只存一个 120 字节的 pointer 文本（指向 LFS 服务器的哈希）
• 真正的二进制存在 GitHub LFS 服务器（按需下载）
• 工作区里你看到的还是真 PNG，操作完全透明

在 wiki-vault 里怎么用

你什么都不用做。 仓库根的 .gitattributes 已经配好，下面后缀自动走 LFS：

类别	跟踪后缀
图片	.png .jpg .jpeg .gif .webp .bmp .tiff .heic（含大写）
视频	.mp4 .mov .webm .mkv .avi .m4v
音频	.mp3 .wav .m4a .flac .ogg
大档案	.pdf .zip .tar .tar.gz .tgz .7z .rar
Office	.docx .xlsx .pptx
设计稿	.psd .ai .sketch .fig .xd

SVG 不走 LFS——它通常很小且是文本，diff 友好。

验证它在工作

冒烟测试范例（2026-04-17 部署当天跑过）：

$ ls -la canon/_assets/test/lfs-smoke.png
-rw-r--r-- 1 root root 1609   # 真 PNG，1.6KB

$ git show HEAD:canon/_assets/test/lfs-smoke.png
version https://git-lfs.github.com/spec/v1
oid sha256:687eb1b6d42b064d811377b806e3d9f0aec7a213a57d83be10216b3ada0aaf66
size 1609

$ git lfs ls-files
687eb1b6d4 * canon/_assets/test/lfs-smoke.png

git 仓库里只存 pointer 文本（120 字节），真二进制在 GitHub LFS。Push 时会看到：

Uploading LFS objects: 100% (1/1), 1.6 KB | 110 KB/s, done.

配额

GitHub LFS 已开通 付费基础版（$5/月）：

• 50 GB 存储
• 50 GB / 月下载流量

按当前 wiki 体量管够。要扩容：在 GitHub Billing 加 data pack（每包 +$5/月，+50G+50G）。不会自动扣，需要人工买，所以不会被坑钱。

同事 clone 后看不到图片怎么办

git lfs install   # 装 git hook（每台机器一次）
git lfs pull      # 拉取所有 LFS 实际文件

如果不装 LFS，工作区里图片会是 120 字节 pointer 文本，浏览器/Obsidian 打不开。

vault-publish skill 在 Step 2 会自动检查并提示这个步骤。

单文件硬上限

GitHub LFS 单文件上限 100 MB。超过会拒收。

超大文件（500MB 视频、超大 PSD）的处理见 wiki图片视频管理规范 §4：建议外链 OSS / B 站 / 飞书云空间，wiki 里只存缩略图 + 链接。

关联

• GitHub — LFS 服务器在 GitHub 这边
• wiki图片视频管理规范 — 完整的资产管理规范、放哪、引用方式
• vault-publish — 发布 skill，自动处理 LFS
• Docs-as-Code 发布架构 — LFS 在整体架构里的位置